package com.mini.grpc.transport;

import com.mini.grpc.common.Metadata;
import com.mini.grpc.common.MethodDescriptor;
import com.mini.grpc.common.Status;

/**
 * ClientTransport接口定义了客户端传输的功能。
 * 
 * <p>客户端传输负责与服务端建立连接并发送请求。
 */
public interface ClientTransport {
    
    /**
     * 创建一个新的流
     *
     * @param method 方法描述符
     * @param headers 请求头
     * @param listener 流监听器
     * @param <ReqT> 请求类型
     * @param <RespT> 响应类型
     * @return 新创建的流
     */
    <ReqT, RespT> ClientStream<ReqT, RespT> newStream(
            MethodDescriptor<ReqT, RespT> method,
            Metadata headers,
            ClientStreamListener<RespT> listener);
    
    /**
     * 启动客户端传输
     * 
     * @return 如果成功启动则返回true，否则返回false
     */
    boolean start();
    
    /**
     * 关闭客户端传输
     * 
     * @param status 关闭状态
     */
    void shutdown(Status status);
    
    /**
     * 检查客户端传输是否已关闭
     * 
     * @return 如果已关闭则返回true，否则返回false
     */
    boolean isShutdown();
    
    /**
     * 检查客户端传输是否已终止
     * 
     * @return 如果已终止则返回true，否则返回false
     */
    boolean isTerminated();
    
    /**
     * 等待客户端传输终止
     * 
     * @throws InterruptedException 如果等待过程被中断
     */
    void awaitTermination() throws InterruptedException;
    
    /**
     * 获取连接状态
     * 
     * @return 连接状态
     */
    ConnectivityState getState();
    
    /**
     * 连接状态枚举
     */
    enum ConnectivityState {
        /**
         * 空闲状态，没有活动的连接
         */
        IDLE,
        
        /**
         * 正在连接
         */
        CONNECTING,
        
        /**
         * 已连接
         */
        READY,
        
        /**
         * 正在断开连接
         */
        TRANSIENT_FAILURE,
        
        /**
         * 已关闭
         */
        SHUTDOWN
    }
} 